Use code to access content from the Kanzi Studio project

In this tutorial you create a widget store where you can browse and select widgets in one view and select widgets to see their descriptions in another view. When running the project at the end of the previous step you saw only the application background. However, the kzb binary file you created from the Kanzi Studio project and loaded in code, includes all the objects you need to create the application logic in code:

A grid list box, into which you load the widget representations in code dynamically. The grid list box sets the layout and interaction behavior for the items it shows.
A widget prefab template, which defines a properties of a widget item in the list of widgets. To add widgets to the list, you generate instances of the prefab with new widget values for name, icon, and description.
Animation clips define animations that highlight the selected widget.
A layer for showing widget descriptions for the selected widget. This layer is initially hidden but is shown when a user selects a widget from the list.
Aliases to access assets from the Kanzi Studio project in the application code.

To access content from the Kanzi Studio project using code:

Include these headers for the function calls that you use in this tutorial.
Use the API reference to find out which headers contain which functions. See API reference.

#include <application/kza_application_interface.h>
#include <application/kza_application.h>
#include <user/animation/kzu_animation_item.h>
#include <user/animation/kzu_animation_clip.h>
#include <user/animation/kzu_animation_player.h>
#include <user/layers/kzu_viewport_layer.h>
#include <user/properties/kzu_fixed_properties.h>
#include <user/properties/kzu_property_registry.h>
#include <user/properties/kzu_property_manager.h>
#include <user/resource/kzu_image_texture.h>
#include <user/resource/kzu_resource_manager.h>
#include <user/scene_graph/kzu_camera.h>
#include <user/scene_graph/kzu_object.h>
#include <user/scene_graph/kzu_object_resources.h>
#include <user/scene_graph/kzu_scene.h>
#include <user/scene_graph/kzu_transformed_scene.h>
#include <user/scene_graph/kzu_transformed_object.h>
#include <user/ui/kzu_ui_domain.h>
#include <user/ui/components/kzu_ui_grid_layout.h>
#include <user/ui/components/kzu_ui_list_box.h>
#include <user/ui/input_manager/kzu_click_manipulator.h>
#include <user/ui/kzu_ui_component.h>
#include <user/ui/message/kzu_general_messages.h>
#include <user/ui/message/kzu_message.h>
#include <user/ui/message/kzu_message_dispatcher.h>
#include <user/ui/templates/kzu_prefab.h>
#include <user/ui/kzu_screen.h>
#include <core/memory/kzc_memory_manager.h>

Create the prefab instances and add them to the grid list box. To do this you need to get access to these assets by loading them from the project. To access the loaded project assets in the application code later, create and store the assets in the ApplicationData structure of the Kanzi application framework. This code contains all application data containers used in this tutorial.

/* Application data container for storing references to objects. */
struct ApplicationData
{
	struct KzuPrefabTemplate*   widgetItemPrefabTemplate;
	struct KzuPropertyType*     widgetDescriptionPropertyType;
	struct KzuObjectNode*       widgetDescriptionLayerNode;
	struct KzuObjectNode*       widgetDescriptionTextBlockNode;
	struct KzuObjectNode*       widgetGridListboxNode;
	struct KzuObjectNode*       cameraObjectNode;
	struct KzuObjectNode*       animationTargetObjectNode;
	struct KzuObjectNode*       backButton;
	struct KzuObjectNode*       currentlySelectedObject;
	struct KzuAnimationItem*    targetAnimationClip;
	struct KzuAnimationItem*    highlightAnimationClip;
	struct KzcMatrix4x4         cameraTransformationTarget;
};

In the KzaApplicationProperties.onProjectLoaded callback implementation, allocate the memory for the structure, and store it to the application.
This code introduces the Kanzi error handling system. All functions that can fail return either an error code containing the error information or KZS_SUCCESS. Intercept this result after every function call and forward it with kzsErrorForward.

KZ_CALLBACK kzsError projectLoaded(struct KzaApplication* application)
{
    kzsError result;
    struct KzcMemoryManager* memoryManager;
    struct ApplicationData* applicationData;

    /* Get the memory manager that is used to create objects. */
    memoryManager = kzaApplicationGetApplicationMemoryManager(application);

    /* Create the application data. */
    result = kzcMemoryAllocVariable(memoryManager, applicationData, "Application data");
    kzsErrorForward(result);

    /* Set application data as user data. */
    kzaApplicationSetUserData(application, applicationData);
    
    ...

    kzsSuccess();
}

You have to free all allocations you allocated and release acquired resources at or before the KzaApplicationProperties.onShutdown callback implementation. For example, the application data is used for the entire application lifetime, so you have to free the memory at the KzaApplicationProperties.onShutdown callback implementation.
Kanzi application framework manages everything you load from the kzb binary. For the rest of the tutorial the freeing of memory allocations is omitted. However, remember to free memory allocations when allocating memory for new instances.
```
KZ_CALLBACK kzsError shutdown(struct KzaApplication* application)
{
    kzsError result;
    struct ApplicationData* applicationData;

    /* Retrieve application data. */
    applicationData = (struct ApplicationData*)kzaApplicationGetUserData(application);

    /* Free application data. */
    result = kzcMemoryFreeVariable(applicationData);
    kzsErrorForward(result);

    kzsSuccess();
}
```

Load the prefab template for widget icons by accessing resource manager through the UI domain object and the grid list box by accessing the Screen object in the scene graph. In this step you can do this in the KzaApplicationProperties.onProjectLoaded callback implementation.
You can access any object in a scene graph using either aliases or full path of the object:

You can create aliases in Kanzi Studio for the objects you access in code. For example, in this tutorial the alias for the Widget Grid List Box is Widget list. In code you access the aliases by adding the hash sign (#) to the alias name. For example, #Widget list. See Aliases.

When using object's full path, start the path with kzb:// followed by the project name and the object's location. For example, to access Widget Item Prefab created in the Prefabs, use kzb://Programmer_tutorial/Prefabs/Widget Item Prefab.
You can find the full paths in the kzb.txt file Kanzi Studio generates when it builds a kzb binary from the Kanzi Studio project. For this tutorial you can find the file in <KanziWorkspace>/Tutorials/Adding code/Start here/Programmer_tutorialApplication/bin.

KZ_CALLBACK kzsError projectLoaded(struct KzaApplication* application)
{
    kzsError result;
    ...
    struct KzuUIDomain* uiDomain = kzaApplicationGetUIDomain(application);
    struct KzuObjectNode* screenNode 
                    = kzuScreenToObjectNode(kzaApplicationGetScreen(application));
    ...
    /* Load references to all required components to application data. */
    {
        /* Get the reference to the reusable prefab (template) for the widget icons. */
        struct KzuResourceManager* resourceManager 
                    = kzuUIDomainGetResourceManager(uiDomain);
        struct KzuResource* resource;
        result = kzuResourceManagerAcquireResource(resourceManager, 
                        "kzb://Programmer_tutorial/Prefabs/Widget Item Prefab", 
                        &resource);
        kzsErrorForward(result);
        applicationData->appPrefabTemplate 
                    = kzuPrefabTemplateFromResource(resource);
 
        /* Get the reference to the grid list box component that contains all widget instances. */
        /* The path is defined by an alias you can create and edit in the Kanzi Studio project. */
        applicationData->widgetGridListboxNode = kzuObjectNodeGetRelative(screenNode, "#Widget list");
    }
    ...

    kzsSuccess();
}

The resource manager tracks the use of resources and deletes unused resources. You can acquire resources from the resource manager using kzuResourceManagerAcquireResource(), which returns an existing resource reference, or creates a new one and loads it. Call kzuResourceRelease to tell the resource manager that a resource handle is no longer used. Make sure that you pair each acquire call with a matching release call as in this code.
```
KZ_CALLBACK kzsError shutdown(struct KzaApplication* application)
{
...
    /* Retrieve application data. */
    struct ApplicationData* applicationData 
                    = (struct ApplicationData*)kzaApplicationGetUserData(application);
    kzsAssert(kzcIsValidPointer(applicationData));

    result = kzuResourceRelease(kzuPrefabTemplateToResource(applicationData->widgetItemPrefabTemplate));
    kzsErrorForward(result);
...
}
```
In the rest of this tutorial the error handling, inclusion of headers and declaration of references in the application data container is omitted.

< PREVIOUS STEP

NEXT STEP >

Open topic with navigation